%slatex-d.tex
%part of
%SLaTeX Version 1.99
%Documentation for SLaTeX
%(c) Dorai Sitaram, December 1991, Rice University

\documentstyle[11pt,slatex]{article}

%\leftcodeskip=2em
%\sloppy
\raggedright
\parskip=1ex
\def\~{\discretionary{}{}{}} % empty discretionary
\let\n\noindent
\def\tm/{$^{\rm tm}$}

\title{How to use SLaTeX}

\author{Dorai Sitaram\\
Department of Computer Science\\
Rice University\\
Houston, TX 77251--1892}

\date{Dec 1991}

\begin{document}
\slatexdisable{enableslatex}

\maketitle

\section{Introduction}

SLaTeX is a Scheme program that allows you to write program
code (or code fragments) ``as is'' in your
LaTeX~\cite{LaTeX} or TeX~\cite{TeX} source.  (See the last
section for using SLaTeX with Plain TeX.) SLaTeX is
particularly geared to the programming languages
Scheme~\cite{RnRS} and other Lisps, e.g., Common
Lisp~\cite{CLtL}.  The formatting of the code includes
assigning appropriate fonts to the various tokens in the
code (keywords, variables, constants, data), at the same
time retaining the proper indentation when going to the
{\it non\/}-monospace (non-typewriter) fonts provided by
TeX.  SLaTeX comes with two databases that recognize the
standard keywords/variables/constants of Scheme and Common Lisp
respectively.  These can be modified by the user using easy
TeX commands.  In addition, the user can inform SLaTeX to
typeset certain identifiers as specially suited LaTeX
expressions (i.e., beyond just fonting them).  All this is
done without interfering with the identifier conventions of
the language of the programming code at all.  In sum, no
change need be made to your (presumably running) program
code in order to get a typeset version suited to the
particular need: you can get a spectrum of styles ranging
from {\it no\/} fonting through basic default fonting to
various ``mathematical''-looking output for pedagogic or
other reasons.

The following section will introduce you to the basic use
of SLaTeX with a small example.  Section~3 gives a complete
description of all the SLaTeX control sequences (which are
listed alphabetically in Appendix~A).  These include
commands for manipulating output positioning, enhancing the
database, changing the fonting defaults, adding special
symbols, and selective disabling of SLaTeX.  Section~4
desribes how to set up a preamble that reflects your
typesetting taste.  Section~5 covers the use of SLaTeX
with plain TeX.  Appendix~B contains information on
obtaining and installing SLaTeX.

\section{A quick illustration of using SLaTeX}

\enableslatex 
 Other packages~\cite{Repository} for typesetting code
fragments use a \verb|verbatim| environment that uses a
monospace {\tt typewriter} font.  This monospace ensures
that the indentation is not affected.  However, the
resulting output fails to distinguish between the various
tokens used in the code, e.g., {\bf boldface} for keywords
like \scheme{define} and \scheme{lambda}, {\sf sans-serif}
for constants like \scheme{#t} and \scheme{42}, and {\it
italics\/} for variables such as \scheme{x} and \scheme{y}
in \scheme{(lambda (x y) (cons x (cons y '())))}.  
\slatexdisable{enableslatex}

The program SLaTeX provides a convenient way of capturing
the indentation information as well as assigning
distinguishing fonts to code tokens without requiring the
user to do worry about fonting and spacing.  It uses
temporary files to store its TeXset version of the user's
code and then calls LaTeX on the user's LaTeX files as well
as these temporaries.

For a quick tutorial on the basic SLaTeX control sequences,
their use, and the running of the SLaTeX program, consider
the following LaTeX ({\it and\/} SLaTeX) file,
\verb|quick.tex|:

\begin{verbatim}
% quick.tex
\documentstyle[11pt,slatex]{article}
\begin{document}

In Scheme, the expression \scheme|(set! x 42)| returns an
unspecified value, rather than \scheme'42'.  However, one
could get a \scheme{set!} of the latter style by:

\begin{schemedisplay}
(extend-syntax (setq)
  [(setq x a)
   (begin (set! x a)
	  x)])
\end{schemedisplay}

\end{document}
\end{verbatim}

Thus, in-text code is introduced by the SLaTeX control
sequence \verb|\scheme| and is flanked by a pair of
identical characters that are not alphabets or \verb|{|.
As a special convenient case, SLaTeX also allows the form
\verb|\scheme{...}|.  The SLaTeX control sequences
(``environment'') for displayed code are the opening
\verb|\begin{schemedisplay}| and the closing
\verb|\end{schemedisplay}|.  One of the
\verb|\documentstyle|s is \verb|slatex|.  (You could also
have written 
\relax ``\verb|\input slatex.sty|'' in your file, where the
file called \verb|slatex.sty| (supplied with SLaTeX)
contains these and other SLaTeX-specific control
sequences.)

The file is now SLaTeX'd by running command \verb|slatex|
(say, from the Un*x command line) on it:

\begin{tabbing}
\hskip4em \verb|slatex quick|   ({\it or\/} \verb|slatex quick.tex|)
\end{tabbing}

This calls a Scheme program that TeXsets the code fragments
identified by the commands \verb|\scheme| and
\verb|\begin|/\verb|\end{schemedisplay}|, and then calls
LaTeX on the result.  The final result is the
\verb|quick.dvi| file, which when viewed or printed, looks
like:

\enableslatex
In Scheme, the expression \scheme|(set! x 42)| returns an 
unspecified value, rather than \scheme'42'.  However, one 
could get a \scheme{set!} of the latter style by:

\begin{schemedisplay}
(extend-syntax (setq)
  [(setq x a)
   (begin (set! x a)
	  x)])
\end{schemedisplay}
\slatexdisable{enableslatex}

\section{The style file}

The LaTeX (or TeX) file that is given to SLaTeX undergoes
some code-setting preprocessing and is then handed over to
LaTeX (or TeX).  The style file \verb|slatex.sty| defines
the appropriate commands so that LaTeX (or TeX) can
recognize the SLaTeX-specific directives and either process
or ignore them.  You may either \verb|\input| the file
\verb|slatex.sty| as usual, or use it as the
\verb|\documentstyle| option \verb|slatex|.

The default database of SLaTeX recognizes the keywords of Scheme.
If you're using Common Lisp, use \verb|cltl.sty| rather than
\verb|slatex.sty|.  \verb|cltl.sty| loads \verb|slatex.sty|
and modifies the database to reflect Common Lisp.  You may
fashion your own \verb|.sty| files on the model of
\verb|cltl.sty|.

\section{SLaTeX's control sequences}

You've already seen the SLaTeX control sequence
\verb|\scheme| and the environment \verb|schemedisplay|.
These suffice for quite a few instances of handling code in
\LaTeX.  However, you will occasionally require more
control on the typesetting process, and the following
complete\footnote{At least that's what you're supposed to
think \ldots} list of SLaTeX control sequences shows you
the ropes.

\begin{description}

\item
\begin{tabular}{l}
\verb|\begin{schemedisplay}|\\
\verb|\end{schemedisplay}|
\end{tabular}

Typesets its argument, which is usually several lines of
indented code, and which is enclosed in arbitrary but
identical characters, as displayed code.  E.g.,

\begin{verbatim}
\begin{schemedisplay}
(define compose          ;this is also known as $B$
  (lambda (f g)
    (lambda (x)
      (apply f (g x)))))
\end{schemedisplay}
\end{verbatim}

produces 

\enableslatex
\begin{schemedisplay}
(define compose        ;this is also known as $B$
  (lambda (f g)           
    (lambda (x)           
      (apply f (g x)))))    
\end{schemedisplay}
\slatexdisable{enableslatex}

Comments in Scheme are usually introduced by `\verb|;|'.
The rest of the line after a `\verb|;|' is set as a line in
LaTeX LR mode.

Separate blocks of code can either be introduced in different
\verb|schemedisplay| environments or put in a single
\verb|schemedisplay| and separated by a line with a
`\verb|;|' in the first column.  This `\verb|;|' is not
typeset and anything following it on the line is set in
LaTeX LR paragraph mode.  I.e., consecutive lines with
`\verb|;|' in the first column are treated as input for a
LaTeX paragraph, with words possibly moved around from line
to line to ensure justification.  E.g.,

\begin{verbatim}
\begin{schemedisplay}
(define even?               ; testing {\it even\/}ness
  (lambda (n)
    (if (= n 0) #t (not (odd? (- n 1))))))
;
; The procedures {\it even?\/} above
; and {\it odd?\/} below are mutually
; recursive.
;
(define odd?              ; testing {\it odd\/}ness
  (lambda (n)
    (if (= n 0) #f (not (even? (- n 1))))))
\end{schemedisplay}
\end{verbatim}

produces 

\enableslatex
\begin{schemedisplay}
(define even?             ; testing {\it even\/}ness
  (lambda (n)
    (if (= n 0) #t (not (odd? (- n 1))))))
;
; The procedures {\it even?\/} above
; and {\it odd?\/} below are mutually
; recursive.
;
(define odd?              ; testing {\it odd\/}ness
  (lambda (n)
    (if (= n 0) #f (not (even? (- n 1))))))
\end{schemedisplay}
\slatexdisable{enableslatex}

Note: see \verb|schemeregion|.

\item
\verb|\scheme|

Typesets its argument, which is enclosed in arbitrary but
identical non-alphabetic and non-\verb|{| characters, as
in-text code.  Special case: \verb|\scheme{...}| is a
convenience (provided the \verb|...| doesn't contain a
\verb|}|) E.g., \verb+\scheme|(call/cc (lambda (x) x))|+
and \verb+\scheme{(call/cc (lambda (x) x))}+ both produce
\enableslatex 
\scheme{(call/cc (lambda (x) x))}.
\slatexdisable{enableslatex}

It is permitted to intermix calls to \verb|schemedisplay|
and \verb|\scheme|.  Thus,

\begin{verbatim}
\begin{schemedisplay}
(define factorial
  (lambda (n)
    (if (= n 0) ; \scheme{(zero? n)} also possible
        1
        (* n (factorial (- n 1)))))) ; or \scheme{... (sub1 1)}
\end{schemedisplay}
\end{verbatim}

produces

\enableslatex
\begin{schemedisplay}
(define factorial
  (lambda (n)
    (if (= n 0) ; \scheme{(zero? n)} also possible
        1
        (* n (factorial (- n 1)))))) ; or \scheme{... (sub1 1)}
\end{schemedisplay}
\slatexdisable{enableslatex}

Note: see \verb|schemeregion|.

\item
\verb|\schemeresult|

Typesets its argument, which is enclosed in arbitrary but
identical non-alphabetic and non-\verb|{| characters, as
in-text Scheme ``result'' or data: i.e., keyword and
variable fonts are disabled.  Special convenient case (as
for \verb|\scheme|): \verb|\schemeresult{...}|.  E.g.,

\begin{verbatim}
\scheme|((lambda () (cons 'lambda 'cons)))| yields
\schemeresult|(lambda . cons)|.
\end{verbatim}

produces

\enableslatex
\scheme|((lambda () (cons 'lambda 'cons)))| yields
\schemeresult|(lambda . cons)|.
\slatexdisable{enableslatex}

\item
\begin{tabular}{l}
\verb|\begin{schemebox}|\\
\verb|\end{schemebox}|
\end{tabular}

The \verb|schemebox| environment is similar to
\verb|schemedisplay| except that the code is provided as a
{\it box\/} (i.e., it is not {\it displayed\/} in the
standard way).  Saving it in an explicit box allows you to
move your typeset code arbitrarily.

Note: see \verb|schemeregion|.

\item
\verb|\schemeinput|

This can be used to input Scheme files as typeset code.
(Unlike LaTeX's \verb|\input|, \verb|\schemeinput|'s
argument must always be grouped.)  The Scheme file is
specified by its full name, or without its extension, if
this is \verb|.ss|.  E.g.,

\begin{verbatim}
\schemeinput{evenodd.ss}    % the .ss is optional!    
\end{verbatim}

(where \verb|evenodd.ss| is the name of a Scheme file
containing the code for 
\enableslatex
\scheme{even?} and \scheme{odd?} above) produces the same
effect as the 
\slatexdisable{enableslatex}
\verb|schemedisplay| version.

Note: see \verb|schemeregion|.

\item
\begin{tabular}{l}
\verb|\begin{schemeregion}|\\
\verb|\end{schemeregion}|
\end{tabular}

Calls to \verb|scheme|, \verb|\schemeresult|,
\verb|schemedisplay|, \verb|schemebox| or
\verb|schemeinput| can be nested in (a Scheme comment) of
other calls.  In LaTeX text, they can occur in bodies of
environments or otherwise grouped.  However, they cannot
normally be passed as arguments to macros or included in
bodies of macro definitions, even though these are complete
calls and not parameterized with respect to macro
arguments.  To be able to do this, you should cordon off
such a text with the \verb|schemeregion| environment.
SLaTeX is fairly generous about where exactly you throw the
cordon.

E.g., you cannot have

\begin{verbatim}
...
The boxed code \fbox{\scheme{(call/cc I)}} is ...
...
\end{verbatim}

\n but you {\it can\/} have

\begin{verbatim}
\begin{schemeregion}
...
The boxed code \fbox{\scheme(call/cc I)}} is ...
... 
\end{schemeregion}
\end{verbatim}

\n and this will produce

\enableslatex
\begin{schemeregion}
\ldots

The boxed code \fbox{\scheme{(call/cc I)}} is \ldots

\ldots
\end{schemeregion}
\slatexdisable{enableslatex}

Thus, the \verb|schemeregion| environment makes it possible
to put SLaTeX-specific commands inside macro arguments or
macro definitions without causing rupture.  Normally, this
can't be done since SLaTeX-specific commands correspond to
\verb|comment|-like regions of LaTeX code once SLaTeX is
done preprocessing your text.  These
\verb|comment| regions share the characteristic of LaTeX's
\verb|verbatim| regions, which also can't appear in macro
arguments or definitions.

To solve this, you enclose the offending text in a
\verb|schemeregion| environment.  This ``inlines'' all the calls to
SLaTeX in its body instead of commenting them and then invoking
\verb|\input|, thus escaping the fate described above.
They are no-ops as far as non-SLaTeX commands are
concerned.  However, while a \verb|schemeregion| allows its
constituent SLaTeX commands to be included in macro
arguments and bodies, it itself cannot be so included.
Thus, your \verb|schemeregion| should be in a position that
satisfies the property A: either directly at the
``top-level'' or in a LaTeX environment that satisfies A.
Since this recursive rule might look weird, you may just
stick to calling \verb|schemeregion| at the ``top-level''.
Or, you may even wrap each of your LaTeX files in one huge
\verb|schemeregion| if you so wish.  This will cover any
obscure ``non-robust'' use of the SLaTeX primitives --
however, SLaTeX will run slower.  (The term ``robust'' is
not necessarily used in the same sense as in LaTeX.)

Note that SLaTeX commands are made robust only if they are
surrounded textually (lexically) by a \verb|schemeregion|.
A region marker doesn't have dynamic scope in the sense
that LaTeX files loaded using \verb|\input| from within a
\verb|schemeregion| will not inherit it.  In summary, a
\verb|schemeregion| makes ``robust'' all calls to
\verb|\scheme|, \verb|schemedisplay|, \verb|schemebox| and
\verb|\schemeinput| within it. 

\item 
\begin{tabular}{l} 
\verb|\setkeyword|\\ 
\verb|\setconstant|\\
\verb|\setvariable| 
\end{tabular} 

SLaTeX has a database containing information about which
code tokens are to be treated as {\bf keywords}, which as
{\sf constants}, and which as {\it variables}.  However,
there will always be instances where the user wants to add
his or her own tokens to these categories, or perhaps even
modify the categories as prescribed by SLaTeX.  The control
sequences that enable the user to do these are
\verb|\setkeyword|,
\verb|\setconstant|, and \verb|\setvariable|.  Their arguments are
entered as a (space-separated) list enclosed in braces (\verb|{}|):
SLaTeX learns that these are henceforth to be typeset in the
appropriate font.  E.g.,

\enableslatex
\begin{verbatim}
\setconstant{infinity -infinity}
\end{verbatim}

\n tells SLaTeX that \scheme{infinity} and
\scheme{-infinity} are to be typeset as constants.  (The
user need not specify such new keywords as are introduced
by Scheme's \scheme{extend-syntax}: SLaTeX automatically
recognizes them.)
\slatexdisable{enableslatex}

\item
\begin{tabular}{l}
\verb|\setspecialsymbol|\\
\verb|\unsetspecialsymbol|
\end{tabular}

These commands are useful to generate
``mathematical''-looking typeset versions of your code,
over and beyond the fonting capabilities provided by
default.  For instance, although your code is restricted to
using ascii identifiers that follow some convention, the
corresponding typeset code could be more mnemonic and
utilize the full suite of mathematical and other symbols
provided by TeX.  This of course should not require you to
interfere with your code itself, which should run in its
ascii representation.  It is only the typeset version that
has the new look.  For instance, you might want all
occurrences of \verb|lambda|, \verb|and|, \verb|equiv?|,
\verb|below?|, \verb|above?|, \verb|a1| and \verb|a2| in
your code to be typeset as $\lambda$, $\land$, $\equiv$,
$\sqsubseteq$, $\sqsupseteq$, $a_1$ and $a_2$ respectively.
To do this, you should \verb|\setspecialsymbol| the
concerned identifier to the desired TeX expansion, viz.

\enableslatex
\begin{verbatim}
\setspecialsymbol{lambda}{$\lambda$}
\setspecialsymbol{and}{$\land$}
\setspecialsymbol{equiv?}{$\equiv$}
\setspecialsymbol{below?}{$\sqsubseteq$}
\setspecialsymbol{above?}{$\sqsupseteq$}
\setspecialsymbol{a1}{$a_1$}
\setspecialsymbol{a2}{$a_2$}
\end{verbatim}
\slatexdisable{enableslatex}

Now, typing 


\begin{verbatim}
\begin{schemedisplay}
(define equiv?
  (lambda (a1 a2)
    (and (below? a1 a2) (above? a1 a2))))
\end{schemedisplay}
\end{verbatim}


\n produces

\enableslatex

\begin{schemedisplay}
(define equiv?
  (lambda (a1 a2)
    (and (below? a1 a2) (above? a1 a2))))
\end{schemedisplay}

\slatexdisable{enableslatex}

Note that with the above settings, \verb|lambda| and
\verb|and| have lost their default keyword status, i.e.
they will not be typed {\bf boldface}.  To retrieve the
original status of special symbols, you should use
\verb|\unsetspecialsymbol|, e.g.

\enableslatex
\begin{verbatim}
\unsetspecialsymbol{lambda and}
\end{verbatim}

Typing the same program after unsetting the special symbols
as above produces, as expected:

\begin{schemedisplay}
(define equiv?
  (lambda (a1 a2)
    (and (below? a1 a2) (above? a1 a2))))
\end{schemedisplay}
\slatexdisable{enableslatex}

In effect, this logically extends the basic ``fonting''
capability to arbitrary special typset versions.

\item
\verb|\schemecasesensitive|

SLaTeX always typesets output that is of the same case as
your input, regardless of the setting of the
\verb|\schemecasesensitive| command.  However, this command
can be used to signal to SLaTeX that all case variations of
an identifier are to be treated identically.  E.g. typing
\verb|\schemecasesensitive{false}| implies that while
\verb|lambda| continues to be a keyword, so also are 
\verb|Lambda|, \verb|LAMBDA| and \verb|LaMbDa|.
\verb|\schemecasesensitive{true}| reverts it back to the
default mode where case is significant in determining the
class of a token.

Note that the status \verb|\schemecasesensitive| also
affects the ``special symbols'' of the previous item.
Thus, in the default case-{\it sensitive\/} setting, only
the case-significant symbol as mentioned in the call to
\verb|\setspecialsymbol| will be replaced by the
corresponding LaTeX expansion.  In a case-{\it
insensitive\/} setting, all case variations of the special
symbol will be replaced.

\item
\begin{tabular}{l}
\verb|\abovecodeskip|\\
\verb|\belowcodeskip|\\
\verb|\leftcodeskip|\\
\verb|\rightcodeskip|
\end{tabular}

These are the parameters used by \verb|schemedisplay| for
positioning the displayed code.  The default values are

\begin{verbatim}
\abovecodeskip=\medskipamount
\belowcodeskip=\medskipamount
\leftcodeskip=0pt
\rightcodeskip=0pt
\end{verbatim}

This produces a flushleft display.  The defaults can be
changed to get new display styles.  E.g.,  the assignment

\begin{verbatim}
\leftcodeskip=5em
\end{verbatim}

\n shifts the display from the left by a constant 5 ems.

On the other hand, the assignments

\begin{verbatim}
\leftcodeskip=0pt plus 1fil
\rightcodeskip=0pt plus 1fil
\end{verbatim}

\n produce a centered display style.

\item
\begin{tabular}{l}
\verb|\keywordfont|\\
\verb|\constantfont|\\
\verb|\variablefont|
\end{tabular}

These decide the typefaces used for keywords, constants,
and variables.  The default definitions are:

\begin{verbatim}
\def\keywordfont#1{{\bf#1}}
\def\constantfont#1{{\sf#1}}
\def\variablefont#1{{\it#1\/}}
\end{verbatim}

This is close to the Little Lisper~\cite{LL} style.
Redefine these control sequences for font changes.  As an
extreme case, defining all of them to \verb|{{\tt#1}}|
typesets everything in monospace typewriter font, as
in~\cite{SICP}.  

\item
\begin{tabular}{l}
\verb|\defschemedisplaytoken|\\
\verb|\defschemetoken|\\
\verb|\defschemeresulttoken|\\
\verb|\defschemeboxtoken|\\
\verb|\defschemeinputtoken|\\
\verb|\defschemeregion|
\end{tabular}

These define the tokens used by SLaTeX to trigger
typesetting of in-text code, display code, box code, and
Scheme files.  The default tokens are, as already
described, \verb|schemedisplay|, \verb|\scheme|,
\verb|\schemeresult|, \verb|schemebox|, \verb|\schemeinput|
and \verb|schemeregion| respectively.  If you want shorter
or more mnemonic tokens, the \verb|\defscheme*token|
control sequences prove useful.  E.g., if you want
\verb|\code| to be your new control sequence for in-text
code, use \verb|\defschemetoken{code}|.  All instances of
\verb|\code+...+| after this definition produce in-text
code, unless overridden by an
\verb|\undefschemetoken| command.

One can have at any time any number of tokens for the same
activity.  One consequence of this is that one can have
nested \verb|schemeregion|s, provided one has different
names for the nested call.  Otherwise, the \verb|\end| of
an inner region will prematurely terminate an outer region.

\item
\begin{tabular}{l}
\verb|\undefschemedisplaytoken|\\
\verb|\undefschemetoken|\\
\verb|\undefschemeresulttoken|\\
\verb|\undefschemeboxtoken|\\
\verb|\undefschemeinputtoken|\\
\verb|\undefschemeregion|
\end{tabular}

These {\it un\/}define the tokens used for triggering
typesetting in-text code, display code, box code, Scheme
files, and robust Scheme regions.  Use these if you want to
use these tokens for other purposes and do not want to
unwittingly trip up the SLaTeX system.

\item
\begin{tabular}{l}
\verb|\defschememathescape|\\
\verb|\undefschememathescape|
\end{tabular}

\verb|\defschememathescape{$}| defines the character
\verb|$| as a mathematical escape character to be used
within scheme code.  (Any character other than \verb|}| and
whitespace may be chosen instead of \verb|$|.)  This allows
one to use LaTeX-like mathematical subformulas within
Scheme code, e.g.,

\begin{verbatim}
\defschememathescape{$}

\begin{schemedisplay}
(define $\equiv$
  (lambda (a$_1$ a$_2$)
    ($\land$ ($\sqsubseteq$ a$_1$ a$_2$) 
	     ($\sqsupseteq$ a$_1$ a$_2$))))     
\end{schemedisplay}
\end{verbatim}

produces

\enableslatex
\defschememathescape{$}

\begin{schemedisplay}
(define $\equiv$
  (lambda (a$_1$ a$_2$)
    ($\land$ ($\sqsubseteq$ a$_1$ a$_2$)
	     ($\sqsupseteq$ a$_1$ a$_2$))))
\end{schemedisplay}

\undefschememathescape{$}
\slatexdisable{enableslatex}

\verb|\undefschememathescape{$}| disables the math-escape nature, if
any, of \verb|$|.

\item
\begin{tabular}{l}
\verb|\slatexdisable|
\end{tabular}

The tokens for typesetting code, as also the token
\verb|\input| (which is sensitive to SLaTeX, since the
latter uses it to recursively process files within files),
can only be used as calls.  If they occur in the bodies of
macro definitions, or their names are used for defining
other control sequences, SLaTeX will not be able to process
them.  Sometimes, one wants to use these tokens, say
\verb|\input|, without having SLaTeX try to process the
inputted file.  Or the name \verb|\scheme| may be used in a
verbatim environment, and we don't want such an occurrence
to trigger the codesetting half of SLaTeX to look for code.

Avoiding such uses altogether can be unduly restrictive
(especially when you're writing a ``How to \ldots''\ paper
like this where you both {\it use\/} and {\it mention\/}
the control sequences!).  One way out is to judiciously use
the \verb|\undefscheme*token| commands to temporarily
remove the SLaTeX-specificity of these names.  Even this
can be painful.  SLaTeX therefore provides the commands
\verb|\slatexdisable|.  This takes one argument word and
makes the corresponding control sequence out of it.
Further, from this point in the text, SLaTeX is disabled
{\it until\/} the manufactured control sequence shows up.
This mechanism makes it possible to restrict SLaTeX to only
appropriate portions of the text.  Note that the token
\verb|\slatexdisable| itself can appear in the text
succeeding its call.  The only token that can restore
SLaTeX-sensitivity is the one created during the call to
\verb|\slatexdisable|.

A typical example of the use of \verb|\slatexdisable| is
when you use the names \verb|\scheme| and
\verb|\begin{schemedisplay}| in a
\verb|verbatim| environment.  E.g.,

\begin{tabbing}
\verb|\slatexdisable{slatexenable}| \\
\verb|\begin{verbatim}| \\
\verb|slatex provides the command \scheme and the pair| \\
\verb|\begin{schemedisplay} and \end{schemedisplay} to typeset| \\
\verb|in-text and displayed Scheme code respectively.| \\
\verb|\end{verbatim}| \\
\verb|\slatexenable| 
\end{tabbing}

\n produces the required

\begin{verbatim}
slatex provides the command \scheme and the pair
\begin{schemedisplay} and \end{schemedisplay} to typeset
in-text and display Scheme code respectively.
\end{verbatim}

\item
\begin{tabular}{l}
\verb|\slatexignorecurrentfile|
\end{tabular}

This is a SLaTeX pragma included to improve efficiency.  If
you're sure that the remaining portion of a certain LaTeX
(or TeX) file (including the files that would be
\verb|\input|ed by it) don't contain any SLaTeX commands,
then you may place this control sequence in it at this
point to signal SLaTeX that no preprocessing is necessary
for the rest of the file.

\end{description}

\section{Setting up a file that resets SLaTeX's defaults} 

A sample style modification file for SLaTeX would include
redefinition of the names of the codesetting control
sequences, adjustment of the display parameters,
modification of the font assignments for
keywords/\~constants/\~variables/\~special symbols, and
addition of new keywords/\~constants/\~variables/\~special
symbols to SLaTeX's database.

Let's assume you want 
\begin{itemize}
\item a centered display style with no vertical skips;

\item the names \verb|\code|, \verb|cdisp|, \verb|cbox|,
\verb|\sinput| instead of 
\verb|\scheme|, \verb|schemedisplay|, \verb|schemebox| and
\verb|\schemeinput|; 

\item tokens to disregard case;

\item the keywords to come out it {\tt typewriter}, the constants in
roman, and the variables in {\sl slant};

\item ``\verb|und|'' and ``\verb|oder|'' as keywords,
``\verb|true|'' and ``\verb|false|'' as constants,
``\verb|define|'' as a variable (overriding default as
keyword!), ``\verb|F|'' as a constant (\verb|f| will also
be a constant, due to case-insensitivity!);

\item ``\verb|top|'' and ``\verb|bottom|'' to print as
$\top$ and $\bot$ respectively.
\end{itemize}

This could be set up as

\begin{verbatim}
\abovecodeskip=0pt
\belowcodeskip=0pt
\leftcodeskip=0pt plus 1fil
\rightcodeskip=0pt plus 1fil

\undefschemetoken{scheme}
\undefschemeboxtoken{schemebox}
\undefschemedisplaytoken{schemedisplay}
\undefschemeinputtoken{schemeinput}

\defschemetoken{code}
\defschemeboxtoken{cbox}
\defschemedisplaytoken{cdisp}
\defschemeinputtoken{sinput}

\schemecasesensitive{false}

\def\keywordfont#1{{\tt#1}}
\def\constantfont#1{{\rm#1}}
\def\variablefont#1{{\sl#1\/}}

\setkeyword{und oder}
\setconstant{true false}
\setvariable{define}

\setspecialsymbol{top}{$\top$}
\setspecialsymbol{bottom}{$\bottom$}
\end{verbatim}

This file can then be \verb|\input|ed in the preamble of
your LaTeX document. 

\section{Using SLaTeX with TeX}

The SLaTeX package can also be used with Plain TeX.  Call
\verb|slatex| on the \verb|.tex| file just as before.
(SLaTeX is clever enough to figure out whether the file it
operates on should later be sent to LaTeX or TeX.)

A couple of remarks on how the \verb|.tex| file should look
-- based on the differences in TeX and LaTeX:
\begin{itemize} 
\item Since TeX doesn't have a
\verb|\documentstyle| command, you have to have an
\verb|\input slatex.sty| command in your \verb|.tex| file.

\item Since TeX doesn't support LaTeX-style environments,
use the pair \verb|\schemedisplay| and
\verb|\endschemedisplay| instead of
\verb|\begin|/\verb|\end{schemedisplay}|; the pair
\verb|schemebox| and \verb|\endschemebox| instead of
\verb|\begin|/\verb|\end{schemebox}|; and the pair
\verb|schemeregion| and \verb|\endschemeregion| instead of
\verb|\begin|/\verb|\end{schemeregion}|.  Note: Do not use
the environment style in TeX or the TeX-style in LaTeX.
\end{itemize}

\appendix

\section{List of SLaTeX control sequences}

\begin{verbatim}
\abovecodeskip 
\begin{schemebox}
\begin{schemedisplay}
\begin{schemeregion}
\belowcodeskip 
\constantfont 
\defschemeboxtoken
\defschemedisplaytoken
\defschemeinputtoken
\defschememathescape
\defschemeregiontoken
\defschemeresulttoken
\defschemetoken
\end{schemebox}
\end{schemedisplay}
\endschemebox            % TeX analogue of \end{schemebox}
\endschemedisplay        % TeX analogue of \end{schemedisplay}
\endschemeregion         % TeX analogue of \end{schemeregion}
\keywordfont
\leftcodeskip
\rightcodeskip
\scheme
\schemebox               % TeX analogue of \begin{schemebox}
\schemecasesensitive
\schemedisplay           % TeX analogue of \begin{schemedisplay}
\schemeinput
\schemeregion            % TeX analogue of \begin{schemeregion}
\schemeresult
\setconstant
\setkeyword
\setspecialsymbol
\setvariable
\slatexdisable
\slatexignorecurrentfile
\undefschemeboxtoken
\undefschemedisplaytoken
\undefschemeinputtoken
\undefschememathescape
\undefschemeregiontoken
\undefschemeresulttoken
\undefschemetoken
\unsetspecialsymbol
\variablefont
\end{verbatim}

\section{How to obtain and install SLaTeX}

SLaTeX is available via anonymous ftp from {\tt
cs.rice.edu} (or {\tt titan.cs.rice.edu}).  Login as {\tt anonymous}, give your userid
as password, change to the directory {\tt public}, convert
to {\tt bin} mode, and get the file {\tt slatex.tar.Z}.
Uncompressing and untarring produces a directory {\tt
slatex}, containing 27 files, viz.: 

\begin{quotation}\tt
\n readme copying install.doc config.ss preproc.ss
funval.cl rnrscl.cl optchez.ss seqprocs.ss fileproc.ss
lerror.ss helpers.ss defaults.ss structs.ss peephole.ss
codeset.ss pathproc.ss texread.ss proctex.ss proctex2.ss
slatex.sty cltl.sty slatex.uni slatex.bat sladebug.uni
sladebug.bat slatex-d.tex
\end{quotation}

\enableslatex
SLaTeX is implemented in R$^4$RS \cite{RnRS} compliant
Scheme (macros are not needed).  The code uses the
non-standard procedures \scheme{delete-file}, \scheme{file-exists?}
and \scheme{flush-output}, but a Scheme without these procedures
can also run SLaTeX (the configuration defines the
corresponding variables to be dummy procedures, since they
are not crucial).
\slatexdisable{enableslatex}

SLaTeX also uses a small shell script for convenient
invocation on your operating system command line.  You may
have to trivially rewrite the shell script if you're not
running Unix or MSDOS.  The distribution comes with code to
allow SLaTeX to run also on Common Lisp.  Please follow the
instructions in {\tt install.doc} to configure SLaTeX for
your system.

SLaTeX has been tested successfully in the following
dialects: Chez~Scheme\tm/ (Kent Dybvig), Common~Lisp\tm/,
MIT~C~Scheme\tm/, Elk\tm/ (Oliver Laumann),
Scheme$\to$C\tm/ (Joel  Bartlett), SCM\tm/ (Aubrey Jaffer)
and UMB~Scheme\tm/ (William Campbell) on Unix\tm/; and
MIT~C~Scheme\tm/ and SCM\tm/ (Aubrey Jaffer) on MSDOS\tm/.
If your Scheme is not mentioned above {\it but is R$^4$RS
\cite{RnRS} compliant}, please send a note to the author at
{\tt dorai@cs.rice.edu} describing your Scheme's procedures
for deleting files, testing file existence, and flushing
output, if any, and the configuration file will be changed
to accommodate the new dialect.

Bug reports are most welcome -- send to {\tt
dorai@cs.rice.edu}.

\begin{thebibliography}{9}
\bibitem{SICP} Harold Abelson and Gerald Sussman with
Julie Sussman. Structure and Interpretation of Computer
Programs.  The MIT Press, 1985.

\bibitem{RnRS} William Clinger, Jonathan Rees et al.
Revised$^4$ Report on the Algorithmic Language Scheme.
November 1991.

\bibitem{LL} Daniel Friedman and Matthias Felleisen.  The
Little Lisper. Science Research Associates, 1989.

\bibitem{TeX} Donald Knuth.  The TeXbook.  Addison-Wesley,
1984.

\bibitem{LaTeX} Leslie Lamport. LaTeX User's Guide and
Reference Manual.  Addison-Wesley, 1986.

\bibitem{CLtL} Guy Steele.  Common Lisp: The
Language.  Digital Press, 1984.  

\bibitem{Repository} Ozan Yigit.  The Scheme Repository at
{\tt nexus.yorku.ca}.
\end{thebibliography}

\end{document}
